.TH E1432_SET_APPEND_STATUS 3 E1432
.SH NAME
.nf
e1432_set_append_status \- Enable/disable appending trailer onto data
e1432_get_append_status \- Get current state of append trailer switch
.fi
.IX e1432_set_append_status(3) 3
.IX e1432_get_append_status(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_set_append_status(E1432ID hw, SHORTSIZ16 ID,
                                   SHORTSIZ16 append)
SHORTSIZ16 e1432_get_append_status(E1432ID hw, SHORTSIZ16 ID,
                                   SHORTSIZ16 *append)
.cE
.SH DESCRIPTION
\fIe1432_set_append_status\fR controls the appending of a trailer of
status data to each block of data.  When turned appending is turned
on, each block of data transfered out of the E1432 module (either to
Local Bus or VME Bus) will have an extra eight 32-bit words appended
to the end of the block.  These extra words contain status information
about that block of data.

\fIe1432_get_append_status\fR returns the current state of append
status, of a single channel or group of channels \fIID\fR, into a
memory location pointed to by \fIappend\fR.

This parameter is a "global" parameter.  It applies to an entire E1432
module rather than to one of its channels.  The \fIID\fR parameter is
used only to identify which module the function applies to, and all
channels in that module will report the same value for this parameter.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

\fIID\fR is either the ID of a group of channels that was obtained with a
call to \fIe1432_create_channel_group\fR, or the ID of a single channel.

\fIappend\fR selects whether or not status information is appended to
a data block.  Specifying \fBE1432_APPEND_STATUS_ON\fR means that an
extra block of status information is appended to the end of each data
block transferred.  \fBE1432_APPEND_STATUS_OFF\fR disables this
feature.  This parameter may also be set with
\fIe1432_set_data_format\fR.

When \fBE1432_APPEND_STATUS_ON\fR is selected, the user is responsible
for reading the additional trailer data from the module.  There are
two ways of doing this, both of which are explained on the read-data
manual pages (\fIe1432_read_raw_data\fR,
\fIe1432_read_float32_data\fR, and \fIe1432_read_float64_data\fR).

One way is to add either 8 or 16 to the size parameter sent to one of
the read-data functions (\fIe1432_read_raw_data\fR,
\fIe1432_read_float32_data\fR, and \fIe1432_read_float64_data\fR).  If
the current data size (as selected by \fIe1432_set_data_size\fR) is
\fBE1432_DATA_SIZE_16\fR, then 16 should be added to the size.
Otherwise, 8 should be added to the size.  This will ensure that the
correct amount of data is read after each data block.  The reason that
the number varies is that the trailer information is always in the
same format, regardless of the current data size setting.  When
reading the data, don't forget to allocate enough room for the extra
trailer data!

The other way to get trailer data is to use the \fItrailer\fR
parameter.  If this is done, then the size parameter to the read data
function should NOT try to account for the additional trailer data.
The \fItrailer\fR parameter should point to an array of
\fIe1432_trailer\fR structures, one for each channel whose data will
be read by this function.

The format of the block of trailer information is given by the
\fIe1432_trailer\fR structure, which is defined in the <e1432.h>
include file.  The structure contains eight fields, each of which is
32-bits wide.  The eight fields are:

.in +3

\fItrig_corr\fR, which specifies the time between the trigger event
and the actual start of data in the block.  The time is normalized to the
data sample interval.  This time is not absolute.
Other, fixed delays are present, which depend on setup conditions.
This field is a 32-bit float.

\fIzoom_corr\fR, which specifies the phase of the local oscillator at
the start of the block.  This is for future use when zoom is
implemented.  It is currently filled with zero.  This field is a
32-bit float.

\fIrpm1\fR, which specifies the RPM on the first tach channel in the
module.  This field contains the RPM only if there is, in fact, a tach
channel, and that tach channel is enabled with \fIe1432_set_active\fR.
The field contains zero otherwise.  This field is a 32-bit float.

\fIrpm2\fR, which specifies the RPM on the second tach channel in the
module.  This field contains the RPM only if there is, in fact, a
second tach channel, and that tach channel is enabled with
\fIe1432_set_active\fR.  The field contains zero otherwise.  This
field is a 32-bit float.

\fIgap\fR, which specifies the number of samples between the start of
this scan and the start of the previous scan.  For the very first scan
of a measurement, the value is the number of samples between the
system sync and the start of the first block.  This field is a 32-bit
integer.

When doing a zoomed measurement (see \fIe1432_set_zoom\fR), the gap
field is set to twice the number of samples between the start of the
scan and the start of the previous scan.  This allows the time between
successive blocks to be calculated using:
.nf
    delay = gap / (span * 2.56)
.fi
This works for both zoom and non-zoom, due to the differing
definitions of span when doing a zoomed measurement.

\fIinfo\fR, which is a bit-field containing information about the
block.  This field is a 32-bit integer.  Here are the bits that may be
present:

.in +3

\fBE1432_TRAILER_INFO_NOT_UNDERRANGE\fR, which indicates that at least
some of the data in this block is above the under-range threshold, so
the next lower input range would overload.  If this bit is zero, then
the next lower input range would not have overloaded due to a
differential overload.

\fBE1432_TRAILER_INFO_OVERLOAD\fR, which indicates that at least some
of the data in this block is overloaded and therefore may not
accurately reflect the input signal.  This bit is set for both
differential and common-mode overloads.  For differential overloads,
increasing the input range may remove the overload.

\fBE1432_TRAILER_INFO_OVERLOAD_COMM\fR, which indicates that at least
some of the data in this block is overloaded due to a common-mode
overload.  If this bit is set, then the above
\fBE1432_TRAILER_INFO_OVERLOAD\fR bit is also set.

\fBE1432_TRAILER_INFO_TRIGGER\fR, which indicates that this input
channel was enabled to trigger and detected a trigger level crossing
within this block.  This does not necessarily mean that this input
channel was the trigger for this data block, since there might have
been another input trigger by another input channel first.

\fBE1432_TRAILER_INFO_SETTLED\fR, which indicates that the data in
this block was collected with properly settled hardware.

\fBE1432_TRAILER_INFO_STOP\fR, which indicates that this is the last
scan of data in the measurement.

\fBE1432_TRAILER_INFO_OT_RAMP_TOO_FAST\fR, which indicates that the
tachometer signal was changing frequency too fast over the time that
resampled data (revolution domain) was being calculated.

\fBE1432_TRAILER_INFO_DEC_2_MASK\fR, which is a set of five bits that,
when shifted down by \fBE1432_TRAILER_INFO_DEC_2_SHIFT\fR, specify the
number of decimate-by-two decimation passes are being performed on the
input data before it is sent to the host.

\fBE1432_TRAILER_INFO_DEC_5\fR, which indicates whether a
decimate-by-five decimation pass is being performed on the input data
before it is sent to the host.

\fBE1432_TRAILER_INFO_CHAN_MASK\fR, which is a set of ten bits that,
when shifted down by \fBE1432_TRAILER_INFO_CHAN_SHIFT\fR, specify the
channel number for the data block.  This channel number is off by one
from the channel number used in the call to
\fIe1432_create_channel_group\fR.  The "off-by-one" is so that the
trailer channel value starts at zero, not one, so that the trailer can
efficiently encode all possible channel numbers.

\fBE1432_TRAILER_INFO_TYPE_MASK\fR, which is a set of three bits that,
when shifted down by \fBE1432_TRAILER_INFO_TYPE_SHIFT\fR, specify the
type of data in the data block.  A value of zero means time data, a
value of (\fBE1432_FREQ_DATA\fR - \fBE1432_TIME_DATA\fR) means
frequency data, and so on.  The values are the same as the data type
that is passed to \fIe1432_read_raw_data\fR, with the value of
\fBE1432_TIME_DATA\fR subtracted out.  This subtraction allows the
value to be encoded efficiently in three bits.

.in -3

\fIpeak\fR, which is the Peak value.
The \fIpeak_mode\fR parameter in the \fIe1432_set_peak_mode\fR function
call determines determines what kind of processing is performed to
produce the value returned in \fIpeak\fR.
A \fIpeak_mode\fR of \fBE1432_PEAK_MODE_OFF\fR turns Peak detection off
and \fIpeak\fR will be set to 0 as a result.
When \fIpeak_mode\fR is \fBE1432_PEAK_MODE_BLOCK\fR,
\fIpeak\fR is the peak of the full span data
across the time period of the block.
When \fIpeak_mode\fR is \fBE1432_PEAK_MODE_FILT\fR,
\fIpeak\fR is same as that returned
by \fIe1432_get_current_value\fR but sampled at the at the trigger point
or the closest point within the time period of the block.

\fIrms\fR, which is the RMS value.
The \fIrms_mode\fR parameter in the \fIe1432_set_rms_mode\fR function
call determines determines what kind of processing is performed to
produce the value returned in \fIrms\fR.
A \fIrms_mode\fR of \fBE1432_RMS_MODE_OFF\fR turns RMS processing off
and \fIrms\fR will be set to 0 as a result.
When \fIrms_mode\fR is \fBE1432_RMS_MODE_BLOCK\fR,
\fIrms\fR is the rms of the full span data
across the time period of the block.
When \fIrms_mode\fR is \fBE1432_RMS_MODE_FILT\fR,
\fIrms\fR is same as that returned
by \fIe1432_get_current_value\fR but sampled at the at the trigger point
or the closest point within the time period of the block.

The weighting, set by \fIe1432_set_weighting\fR
applies to both \fIpeak\fR and \fIrms\fR.
Both \fIpeak\fR and \fIrms\fR are only available at clock frequencies
of 65,536 or less.
Currently both \fIpeak\fR and \fIrms\fR are the result of processing the
full span data, not the decimated data.

.in -3

The trailer data is one way to get status information about the data,
and is the most common way to get this information.  An alternative is
to use the \fBE1432_DATA_SIZE_32_SERV\fR value for data size (see
\fIe1432_set_data_size\fR), though this does not contain as much
information.
.SH "RESET VALUE"
After a reset, \fIappend\fR is set to \fBE1432_APPEND_STATUS_OFF\fR.
.SH "RETURN VALUE"
Return 0 if successful, a (negative) error number otherwise.
.SH "SEE ALSO"
.na
e1432_read_raw_data, e1432_read_float32_data,
e1432_read_float64_data, e1432_set_clock_freq, e1432_set_data_size,
e1432_set_peak_mode, e1432_set_rms_mode,
e1432_set_weighting, e1432_set_zoom.
.ad
